The Utilities Experience/The Utilities Experience - Volume 1.iso/software/graphics/a-g/beyondthedark/developer/docs/btdsub.doc

Text File | 1995-12-21 | 5.0 KB | 180 lines

TABLE OF CONTENTS

blanker.btd/--background--
blanker.btd/AnimBlanker
blanker.btd/EndBlanker
blanker.btd/InitBlanker
blanker.btd/PenCountBlanker
blanker.btd/QueryBlanker

blanker.btd/--background--

Blanker modules for Beyond The Dark are AmigaOS shared libraries with 5
standard functions described in this document.

These libraries should follow the guide lines listed in the "AMIGA ROM
Kernel Reference Manual: Libraries" with one additional    feature: the
library base MUST be sharable between different tasks.

Because of this requirement you must NOT use SAS/C's library startup code.
The source code of a generic library startup code for blanker modules is
included. Of course you haven't got to use it, it's just an option to make
your life easier.

Always remember that your code MUST be reentrant, so be careful with
global variables. Don't make any assumptions about the supplied RastPort
(it may or may not have a layer), the order of the pens or the size and
the offset of the drawing box. Always use BTD_BgPen for the background.

Various examples for blanker modules are included. The best way to learn
is to look at them. If you still have questions contact me.

    Matthias Scheler <[e-mail]>
blanker.btd/AnimBlanker                                 blanker.btd/AnimBlanker

   NAME
    AnimBlanker() -- animate a blanker


   SYNOPSIS
    AnimBlanker(data);
                A0

        void AnimBlanker(APTR);

   FUNCTION
    Draws a "frame" of the blanker's graphics.

   NOTE
    There are no rules what a "frame" is. "Hop.btd" e.g. will plot a
    single pixel in a "frame", "ASwarm.btd" will move all wasps and
    bees.

    If you want to synchronize your blanker with the raster beam call
    WaitTOF() yourself.

    Don't use CPU busy loops e.g. by using graphics.library/WaitBOVP()
    because other blanker modules could use the CPU time much better.

   EXAMPLE
    /* plot something with the 2nd pen */
    SetAPen (BTDDrawInfo->BDI_RPort,BTDDrawInfo->BDI_Pens[1]);
    WritePixel (BTDDrawInfo->BDI_RPort,X,Y);

    /* set the 3rd color to white */
    BTDDrawInfo->BDI_Red[BTDDrawInfo->BDI_Pens[2]]=255;
    BTDDrawInfo->BDI_Green[BTDDrawInfo->BDI_Pens[2]]=255;
    BTDDrawInfo->BDI_Blue[BTDDrawInfo->BDI_Pens[2]]=255;
    BTDDrawInfo->BDI_Changed[BTDDrawInfo->BDI_Pens[2]]=TRUE;

   SEE ALSO
    <BTD.h>, EndBlanker(), InitBlanker(), PenCountBlanker()

blanker.btd/EndBlanker                                   blanker.btd/EndBlanker

   NAME
    EndBlanker() -- free a blanker's private data

   SYNOPSIS
    EndBlanker(data);
                A0

        void EndBlanker(APTR);

   FUNCTION
    Frees blanker's private data created with InitBlanker().

   INPUTS
    data - pointer to blanker's private data

   SEE ALSO
    <BTD.h>, AnimBlanker(), InitBlanker(), PenCountBlanker()

blanker.btd/InitBlanker                                 blanker.btd/InitBlanker

   NAME
    InitBlanker() -- initialize a blanker's private data

   SYNOPSIS
    data = InitBlanker(tagList);
    D0                 A0

        APTR InitBlanker(struct TagItem *);

   FUNCTION
    Initialize the data structures required for the blanker.

   NOTE
    The contents of the structure is completely private. Programs which
    use blanker libraries should NOT make any assumptions about it.

    The BTDDrawInfo structure will be valid until the EndBlanker()
    call. Blanker modules haven't to copy it but it's a good idea to
    store the pointer somewhere in the private date structure.

   INPUTS
    tagList - list of tag items with various parameters, the tag
              BTD_DrawInfo with a pointer to a BTDDrawInfo structure
              should be among them.

   RESULTS
    data - pointer to a structure which can be passed to AnimBlanker()
           or EndBlanker(). If the initialization fails, zero will be
           returned.

   SEE ALSO
    <BTD.h>, AnimBlanker(), EndBlanker(), PenCountBlanker()

blanker.btd/PenCountBlanker                         blanker.btd/PenCountBlanker

   NAME
    PenCountBlanker() -- count required pens

   SYNOPSIS
    pens = PenCountBlanker(tagList);
    D0                     A0

        ULONG PenCountBlanker(struct TagItem *);

   FUNCTION
    Determines how many pens a blanker requires. It gets the same
    parameters which will later be passed to InitBlanker() except
    the tag BTD_DrawInfo.

   NOTE
    The result of this function MUST be correct. If the module
    requires more pens than returned by PenCountBlanker() there
    will be a problem.

   INPUTS
    tagList - list of tag items with various parameters

   RESULTS
    pens - number of pens required for these parameters

   SEE ALSO
    <BTD.h>, AnimBlanker(), EndBlanker(), InitBlanker()

blanker.btd/QueryBlanker                               blanker.btd/QueryBlanker

   NAME
    QueryBlanker -- get information about blanker sub library

   SYNOPSIS
    info = QueryBlanker();
    D0

    struct BTDInfo *QueryBlanker(void);

   FUNCTION
    Returns a pointer to a structure with informations about the blanker
    sub library. These informations are used to verify that the library
    is compatible with the actual interface definition, to identify the
    blanker and to build up the preferences window for it.

   RESULTS
    info - pointer to the blanker informations

   SEE ALSO
    <BTD.h>